                     Digital Distortion Login Matrix
                              Version 1.09
                        Release date: 2013-05-27

                                  by

                             Eric Oulashin
                     Sysop of Digital Distortion BBS
                 BBS internet address: digdist.bbsindex.com
                     Email: eric.oulashin@gmail.com



This file describes the Digital Distortion Login Matrix.

Contents
========
1. Introduction
2. Installation & Setup
3. Main configuration file
4. Themes & theme configuration files
5. Multi-lingual support


1. Introduction
===============
This package contains a login matrix for Synchronet, written in JavaScript.
This script is designed to run when a user connects to the BBS.  When a
user connects, they will be presented with a menu containing options to
log in, create a new account, use the guest account (if available), email
the sysop, and page the sysop.  Additionally, a background ANSI/ASCII file
will be displayed behind the menu.  When the user chooses the option to log
in, another file (or perhaps the same file) is displayed for the background,
and the user is prompted for their username and password via text boxes.

This matrix is configurable with options for enabling/disabling the guest,
page sysop, and email sysop options on the menu.  Also, this login matrix
has support for "themes", where each theme is in its own subdirectory
containing background files and its own configuration file.  Each theme's
configuration file can specify the background files for initial connection
and username/password entry, as well as various options such as location
of the menu, menu colors, and locations & colors of the username &
password boxes.

The login matrix only works with ANSI terminals; however, you don't need to
worry about checking for non-ANSI users, because the script will perform a
traditional Synchronet login for non-ANSI users.

Another feature of this login matrix is that it has multi-lingual support via
the use of language files, so it's possible to change the language of
your matrix by adding/creating a new language file (see section 5: Multi-
lingual support).

Note: I have included some themes with the script.  The background screens
in the dd-eye theme were created by me; however, the background screens in
the other themes were created by other people.  Recognition goes out to
those other artists for their work.


2. Installation & Setup
=======================
These are the steps for installation:
 1. Unzip the archive.  If you're viewing this file, then you've probably
    already done this. :)
 2. Place the files and directories in a directory of your choice.  It is
    recommended that the files be placed in their own directory, because
    there are several files and subdirectories.  These are the files and
    directories that you will need to place together:
    DDLoginMatrix.js
    DDLoginMatrix.cfg
    DDLoginMatrixLangFiles
    DDLoginMatrixThemes
 3. Edit your login.js file (normally in the SBBS exec directory) to load
    the matrix script rather than run its own code.

Step 3 deserves a more detailed explanation.  For these instructions, I will
assume that the files in this archive were placed in sbbs/xtrn/DigDist.
login.js needs to be edited to contain ONLY the following line:
load("../xtrn/DigDist/DDLoginMatrix.js", "digdist/answer");

Note, again, that this assumes the matrix files are placed in
sbbs/xtrn/DigDist.  Also, note the second parameter: This specifies a file
in the SBBS text/menu directory to display when a non-ANSI user connects to
your BBS.
Rather than editing login.js, I would recommend creating a new login script
(with a name such as loginDD.js).  The reason is that login.js is included
with the standard Synchronet releases, and if you use login.js, it's possible
to accidentally overwrite your modifications when upgrading to newer versions
of Synchronet in the future.  You can change the login script that is used
by loading the Synchronet configuration program (SCFG) and choosing
System > Loadable Modules.  The setting to change is "Login".  As an example,
if you created a new login script called loginDD.js, you would type loginDD
here.

Alternately, you could place all of the Digital Distortion Matrix files
into the SBBS exec directory and specify DDLoginMatrix.js as the Login
module in the Synchronet configuration program.


3. Main configuration file
==========================
The main configuration file, DDLoginMatrix.cfg, contains settings for the
behavior of the matrix.  The syntax for each line in the file is as
follows:
Option=Value
where Option is the option to set, and Value is the setting for that option.

The following is a description of the configuration file options:

Option                                Description
-------                               -----------
UseMatrix                             Whether or not to use the matrix-style
                                      login.  (If not, a more traditional style
                                      login will be used).  Valid values are
                                      Yes and No.

MenuTimeoutMS                         The menu input timeout, in milliseconds.
                                      If no input is received from the user
                                      within this amount of time, the script
                                      will disconnect.

MenuDisplayNewUser                    Whether or not to display the new user
                                      option in the menu.  Valid values are
                                      Yes and No.

MenuDisplayGuestAccountIfExists       Whether or not to display the menu option
                                      for the guest account, if available.
                                      Valid values are Yes and No.

MenuDisplayRetrievePassword           Whether or not to display the menu option
                                      to let the user retrieve their password.
                                      Valid values are Yes and No.

MenuDisplayEmailSysop                 Whether or not to display the menu
                                      option for emailing the sysop.  Valid
                                      values are Yes and No.

MenuDisplayPageSysop                  Whether or not to display the menu option
                                      for paging the sysop.  Valid values are
                                      Yes and No.

MaxLoginAttempts                      The maximum number of login attempts to
                                      allow before disconnecting the user.

AllowUserNumber                       Whether or not to allow logging in by
                                      user number (this is in addition to
                                      logging in via username).  Valid values 
                                      are Yes and No.

MatrixTheme                           The directory name of the theme to use.
                                      This can also be Random to tell the
                                      matrix script to select a random theme
                                      each time a user logs in.

Language                              Specifies the name of the language to
                                      use.  The text for the language will
                                      be loaded from a file in the
                                      DDLoginMatrixLangFiles directory, with
                                      the filename Language.lng, where Language
                                      is the language specified here.

SoundFile                             A name of a sound file to play when a
                                      user logs in successfully. Note: As of
                                      this writing (February 11, 2011),
                                      Synchronet only supports playing a sound
                                      in Windows.
                                      

PlaySound                             Whether or not to play the login sound.
                                      Valid values are Yes and No.


4. Themes & theme configuration files
=====================================
The DDLoginMatrixThemes directory contains the themes, where each theme is in
its own subdirectory.  Each theme subdirectory contains the following files:
- A file to display when the user connects
- Optional: Another file to display when the user is prompted for their
  username and password
- DDMatrixTheme.cfg: The theme's configuration file.  Each line of this
  configuration file is in the format of Option=Value.

The following is a list of the theme configuration options:

Option                                Description
-------                               -----------
InitialBackgroundFilename             The name of a file to display when a user
                                      connects.  Note that this should not
                                      include the extension.

LoginBackgroundFilename               The name of a file to display when the
                                      user is prompted for their username and
                                      password.  The value can be the same as
                                      InitialBackgroundFilename.  If this value
                                      is blank, the screen will simply be
                                      cleared before prompting for the
                                      user's username & password.

MenuX                                 The horizontal cursor position of the
                                      top-left corner of the matrix menu.

MenuY                                 The vertical cursor position of the
                                      top-left corner of the matrix menu.

MenuBorders                           The border style of the matrix menu.
                                      This can be Single or Double.

ClearSpaceAroundMenu                  Whether or not to clear a space around
                                      the matrix menu (to help it stand out).
                                      Valid values are Yes and No.

MenuTitle                             The text to display above the matrix menu

DisplayMenuTitle                      Whether or not to display the menu title.
                                      Valid values are Yes and No.

MenuColor_Border                      The color to use for the menu border

MenuColor_Unselected                  The color to use for non-selected menu
                                      items

MenuColor_Selected                    The color to use for selected menu items

MenuColor_Hotkey                      The color to use for menu item hotkeys

MenuColor_ClearAroundMenu             The color to use when clearing a space
                                      around the menu

UsernameX                             The horizontal cursor position of the
                                      top-left corner of the username box

UsernameY                             The vertical cursor position of the
                                      top-left corner of the username box

UsernameLength                        The maximum allowed username input length

UsernameBoxBorderColor                The color to use for the border of the
                                      username box

UsernameBoxBkgColor                   The color to use when clearing the inside
                                      of the username box

UsernamePromptColor                   The color to use for the username prompt
                                      text

UsernameTextColor                     The color to use for the user's inputted
                                      username

PasswordX                             The horizontal cursor position of the
                                      top-left corner of the password box

PasswordY                             The vertical cursor position of the
                                      top-left corner of the password box

PasswordLength                        The maximum allowed password input length

PasswordBoxBorderColor                The color to use for the border of the
                                      password box

PasswordBoxBkgColor                   The color to use when clearing the inside
                                      of the password box

PasswordPromptColor                   The color to use for the password prompt
                                      text

PasswordTextColor                     The color to use for the user's inputted
                                      password

StatusX                               The horizontal cursor position of the
                                      top-left corner of the status box
                                      (displayed when the user is prmopted
                                      for their username & password)

StatusY                               The vertical cursor position of the
                                      top-left corner of the status box
                                      (displayed when the user is prmopted
                                      for their username & password)

StatusBoxInnerWidth                   The inner width to use for the status box
                                      (displayed when the user is prompted for
                                      their username & password)

StatusBoxBorderColor                  The color to use for the border of the
                                      status box
                                      (displayed when the user is prmopted
                                      for their username & password)

StatusBoxBkgColor                     The color to use when clearing the inside
                                      of the status box (displayed when the user
                                      is prmopted for their username & password)

StatusTextColor                       The color to use for the status text
                                      (displayed when the user is prmopted
                                      for their username & password)

5. Multi-lingual support
========================
This login matrix supports multiple languages via the use of files stored in
the DDLoginMatrixLangFiles containing the text strings for different languages.
Each line in the language file contains a specifier and text string, in the
following format:
specifier=string

Furthermore, the language files are divided into 3 sections, with the following
headers:
[MATRIX] - These strings are used in matrix mode
[STANDARD] - These strings are used in the standard (non-matrix) login mode
[GENERAL] - These strings are various strings used for both modes.

The specifiers are in English, but the strings contain the actual language text.
The following is a list of the specifiers and what they are used for:
[MATRIX]  (Matrix mode text)
LOGIN: The text for the login menu option (Note: An ampersand (&) precedes a shortcut character)
NEWUSER: The text for the New User menu option
GUEST: The text for the Guest Account menu option
RETRIEVE_PASSWORD: The text for the menu option to retrieve a password
EMAIL_SYSOP: The text for the menu option to email the sysop
PAGE_SYSOP: The text for the menu option to page the sysop
DISCONNECT: The text for the menu option to disconnect
USERNAME_NUM_PASS_PROMPT: The text used to let the user know to enter their username or number.
                          Note: Only this one OR the next one will be used.
USERNAME_PASS_PROMPT: The text used to let the user know to enter their username (not allowing
                      user number input).  Note: Only this one OR the previous one will be
                      used, depending on the configuration settings.
USERNAME_OR_NUM_PROMPT: The prompt text for the user's username/number.  Note: Only this
                        one OR the next one will be used, depending on the configuration
                        settings.
USERNAME_PROMPT: The prompt text for the user's username.  Note: Only this one OR the
                 previous one will be used, depending on the configuration settings.
PASSWORD_PROMPT: The text to use for the password prompt
UNKNOWN_USERNAME_OR_NUM: The error message displayed when the user enters an unknown
                         username or number.  Note: Only this one OR the next one
                         will be used, depending on the configuration settings.
UNKNOWN_USERNAME: The error message displayed when the user enters an unknown username.
                  Note: Only this one OR the previous one will be used, depending on the
                  configuration settings.
LOGIN_ATTEMPTS_FAIL_MSG: The error message to display after the user fails all login attempts
GUEST_ACCT_FAIL: The error message to display if the guest account can't be used
SYSOP_HAS_BEEN_PAGED: The message to display to let the user know the sysop has been paged
UNABLE_TO_PAGE_SYSOP: The message to display if the sysop can't be paged right now
LOGOFF_CONFIRM_TEXT: The text to use for the question to confirm if the user really wants
                     to log off
DISCONNECT_MESSAGE: The message to display before disconnecting the user when the user
                    chooses to disconnect
INPUT_TIMEOUT_REACHED: The message to display when the input timeout has been reached
INVALID_LOGIN: The text "Invalid login", or the equivalent in another language

[STANDARD]  (Standard (non-matrix) mode text)
USERNAME_PROMPT: The text to use to tell the user to enter their username
OR_NUMER_PROMPT: The text " or number", displayed if user number logins are supported
NEW_USER_INFO: The text to tell the user how to log in as a new user
GUEST_INFO: The text to tell the user how to log into the guest account
LOGIN_PROMPT: The text to use for the login prompt
PASSWORD_PROMPT: The text to use for the password prompt

[GENERAL]   (General text strings)
NEW: The word "new" (in the respective language)
EMAIL_ADDR_CONFIRM_PROMPT: The text to use when having the user confirm their email
                           address (for password retrieval)
DID_YOU_FORGET_PASSWORD_CONFIRM: The text to use for asking the user if they forgot
                                 their password (for password retrieval)
ACCT_INFO_REQUESTED_ON_TIME: Used when emailing a user their password, this text
                             is displayed before the time their information was
                             requested.
BY: The word "by" (in the respective language)
VIA: The word "via" (in the respective languge)
PORT: The word "port" (as applied to network ports, in the respective language)
INFO_ACCT_NUM: Used when emailing a user their password, this text
               is displayed before the user's account number
INFO_CREATED: Used when emailing a user their password, this text
              is displayed before the user's account creation date
INFO_LAST_ON: Used when emailing a user their password, this text
              is displayed before the user's last logon date/time
INFO_CONNECT: Used when emailing a user their password, this text
              is displayed before the user's connection type used when requesting
              their information
INFO_PASSWORD: Used when emailing a user their password, this text
               is displayed before the user's password
INFO_INCORRECT_EMAIL_ADDR: This is the error message displayed if the user
                           enters an incorrect email address when asked to
                           confirm theirs.
ACCT_INFO_EMAILED_TO: Used when emailing a user their password, this text
                      is displayed to show the address where their information
                      was emailed to.
ERROR_SAVING_BULKMAIL_MESSAGE: Used when emailing a user their password, this is
                               an error message to display if there was a problem
                               saving the mail.
UNKNOWN_USERNAME: This is an error message telling the user that their username is
                  unknown (used for password retrieval).
UNABLE_TO_RETRIEVE_ACCT_INFO: This is an error message displayed if the login
                              script is unable to send the user their account
                              information (i.e., if their email address is not
                              valid, if they are the sysop, etc.).